Command Reference

Use this section to reference skill capabilities, available commands, keywords, expected inputs, and predicted outputs.

Parsing Results and Detecting Failure

Pass --json to any command that supports it to get a single, stable envelope on stdout:

Copy

json

{
  "schemaVersion": "1.0",
  "command": "<canonical command path>",
  "status": "ok" | "error",
  "data": { /* present when status is ok */ },
  "error": { "code": "<machine code>", "message": "...", "hint": "...", "details": { } },
  "warnings": ["..."]
}

Top-Level Commands

ods connect

Connect and authenticate with a OneStream server.

Arguments	<`serverUrl`>. OneStream server URL, for example https://myserver.onestream.com.
Safety	Read. Safe to run autonomously and makes no changes.

Copy

ods connect https://myserver.onestream.com

ods disconnect

Disconnect and clear stored credentials.

Prerequisites	You must be connected first: `ods connect <serverUrl>`
Safety	Read. Safe to run autonomously and makes no changes.

Copy

ods disconnect

ods extract

Extract (pull) the items described by a single .xfproj manifest out of the connected application. By default, the project is expanded to disk in place next to the .xfproj.

NOTE: The --zip flag saves a single packaged zip. This operation requires OneStream Platform Version 9.4.0 or later.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Arguments	`<file>`: the Path to the .xfproj manifest.
Options	`--zip`: save the packaged .zip instead of expanding to disk. `--out <path>`: output directory for the packaged zip . This is `--zip` only and defaults to the .xfproj folder.
Safety	Destructive. This requires explicit human confirmation. Never auto-pass `--yes`. Preview first where a preview command exists.
Supports	`--json`. This emits the standard envelope.

Copy

ods extract ./MyApp.xfproj
ods extract ./MyApp.xfproj --zip --out ./dist

ods load

Load (push) the items described by a single .xfproj manifest into the connected application.

NOTE: This requires OneStream Platform Version 9.4.0 or later.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Arguments	`<file>`: the Path to the .xfproj manifest.
Options	`--mode <mode>`: load mode. Merge (additive) or replace (deletes server content first). This is required.
Safety	Destructive. This requires explicit human confirmation. Never auto-pass `--yes`. Preview first where a preview command exists.
Supports	`--json`. This emits the standard envelope.

Copy

ods load ./MyApp.xfproj --mode merge
ods load ./MyApp.xfproj --mode replace --yes

ods preview-pull

Compares the server against local items and reports what a pull would change.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Arguments	`[paths...]`: mapping files or directories to process. Defaults to the current working directory.
Options	`--diff`: Include inline unified diffs in the text output.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods preview-pull
ods preview-pull . --diff
ods preview-pull --json

ods preview-push

Compares local items against the server and reports what a push would change.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Arguments	`[paths...]`: mapping files or directories to process. Defaults to the current working directory.
Options	`--diff`: Include inline unified diffs in the text output.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods preview-push
ods preview-push . --diff
ods preview-push --json

ods pull

Pulls the resolved repository items (.osmap) from the connected application, overwriting local files. The item kind is inferred from each mapping file.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Arguments	`[paths...]`: mapping files or directories to process. Defaults to the current working directory.
Options	`--diff`: Include inline unified diffs in the text output.
Safety	Destructive. This requires explicit human confirmation. Never auto-pass `--yes`. Preview first where a preview command exists.
Supports	`--json`. This emits the standard envelope.

Copy

ods pull
ods pull ./src/MyRule
ods pull . --yes

ods push

Push the resolved repository items (.osmap) to the connected application. The item kind is inferred from each mapping file.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Arguments	`[paths...]`: mapping files or directories to process. Defaults to the current working directory.
Options	`--diff`: Include inline unified diffs in the text output.
Safety	Destructive. This requires explicit human confirmation. Never auto-pass `--yes`. Preview first where a preview command exists.
Supports	`--json`. This emits the standard envelope.

Copy

ods push
ods push ./src/MyRule
ods push . --yes

ods status

Shows current connection status.

Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods status
ods status --json

ods update

Checks if a newer CLI version is available.

Options	`--check`: check for a newer version without installing (read-only).
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods update --check
ods update --check --json

ods validate

Validates the resolved repository items (.osmap) locally.

Arguments	`[paths...]`: mapping files or directories to process. Defaults to the current working directory.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods validate
ods validate ./src/MyRule
ods validate . --json

Agent Commands

ods agent skill init

Generates the skill bundle (SKILL.md + references/commands.md + references/xf-project.md) into a target path. The default is the current directory. You can optionally wire a tool entrypoint with --tool. The command reference is generated from the CLI itself, so it never drifts from the real command surface.

Arguments	`[name]`: the skill to generate. This defaults to the CLI. `[path]`: the target directory. This defaults to the current working directory.
Options	`--tool <tool>`: wire a tool entrypoint. The options are cursor, claude, copilot, or all.
Safety	Mutating (non-destructive). This may run autonomously. The agent may pass `--yes` to skip the interactive prompt.
Supports	`--json`. This emits the standard envelope.

Copy

ods agent skill init
ods agent skill init cli ./my-app --tool cursor
ods agent skill init --tool all

ods agent skill list

Lists the named skills available to ods agent skill init. With --json, this emits the array for scripting and agents.

Alias	`ls`
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods agent skill list
ods agent skill list --json

Application Commands

ods application clear

Clears the currently selected application.

Safety

Read. Safe to run autonomously and makes no changes.

Copy

ods application clear

ods application current

Shows the currently selected application.

Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods application current
ods app current --json

ods application list

Lists available applications from the connected server.

Prerequisites	You must be connected first: `ods connect <serverUrl>`
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods application list
ods app list --json

ods application use

Selects the current application for push/pull operations.

Prerequisites	You must be connected first: `ods connect <serverUrl>`
Alias	`set`
Arguments	`<name>`: name of the application to use
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods application use GolfStream
ods app use GolfStream

Business Rule Commands

ods business-rule add

Creates a new business rule with project and mapping files.

Arguments [path]: project directory or file. This defaults to the current working directory.

Options

-n, --name <name>: Name for the repository item.

-l, --language <language>: programming language. CSharp or VisualBasic.

-e, --existing: use an existing project instead of creating one.

--assemblyName <assemblyName>: OneStream assembly or business rule name.

-b, --businessRuleType <businessRuleType>: business rule type.

Safety

Mutating (non-destructive). This may run autonomously. The agent may pass --yes to skip the interactive prompt.

Copy

ods business-rule add -n MyRule

ods business-rule decrypt

Decrypts a specific business rule on the connected server.

Prerequisites

You must be connected first: ods connect <serverUrl>

An application must be selected: ods application use <name> or pass --application <name>.

Options

-n, --name <name>: OneStream business rule name.

--password-stdin: read the decryption password from stdin.

Safety

Destructive. This requires explicit human confirmation. Never auto-pass --yes. Preview first where a preview command exists.

Copy

ods br decrypt -n MyRule
echo "$PASSWORD" | ods br decrypt -n MyRule --password-stdin

ods business-rule edit

Edits an existing business rule mapping file.

Arguments [path]: mapping file or directory. This defaults to the current working directory.

Options

-n, --name <name>: name of the repository item. This is used to find the <name>.osmap file in a directory.

--assemblyName <assemblyName>: OneStream assembly or business rule name.

-b, --businessRuleType <businessRuleType>: business rule type.

Safety

Mutating (non-destructive). This may run autonomously. The agent may pass --yes to skip the interactive prompt.

Copy

ods business-rule edit -n MyRule

ods business-rule encrypt

Encrypts a specific business rule on the connected server.

Prerequisites

You must be connected first: ods connect <serverUrl>

An application must be selected: ods application use <name> or pass --application <name>.

Options

-n, --name <name>: OneStream business rule name.

--password-stdin: read the encryption password from stdin. This is for non-interactive use.

Safety

Destructive. This requires explicit human confirmation. Never auto-pass --yes. Preview first where a preview command exists.

Copy

ods br encrypt -n MyRule
echo "$PASSWORD" | ods br encrypt -n MyRule --password-stdin

ods business-rule get

Gets a specific business rule from the connected server.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Arguments	`<name>`: OneStream business rule name.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods br get MyRule
ods br get MyRule --json

ods business-rule list

Lists all business rule items. Local mapping files by default or server items with --remote.

Aliases	`ls`
Arguments	`[path]`: the path to list local items from. This defaults to the current working directory. This is ignored with `--remote`.
Options	`--remote`: list items on the connected server instead of local mapping files. `--type <type>`: filter server results by business rule type. This requires `--remote`.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods br list
ods br list --json
ods br list --remote
ods br list --remote --json
ods br list --remote --type Finance

ods business-rule remove

Removes business rule mapping files.

Aliases	`rm`
Arguments	`[path]`:mapping file or directory. This defaults to the current working directory.
Safety	Destructive. This requires explicit human confirmation. Never auto-pass `--yes`. Preview first where a preview command exists.

Copy

ods business-rule remove ./src/MyItem

ods business-rule types

Enumerates the business rule types the platform recognizes. This requires an authenticated connection. No application selected is needed.

Prerequisites	You must be connected first: `ods connect <serverUrl>`
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods br types
ods br types --json

Config Commands

ods config get

Gets a config value by key.

Arguments	`<key>`: config key.
Safety	Read. Safe to run autonomously and makes no changes.

Copy

ods config get authorityUrl

ods config list

Lists all config key-value pairs.

Safety

Read. Safe to run autonomously and makes no changes.

Copy

ods config list

ods config server list

Lists all server-specific configurations.

Safety

Read. Safe to run autonomously and makes no changes.

Copy

ods config server list

ods config server remove

Removes all configuration from a server.

Arguments	`<serverUrl>`: server URL to remove config for.
Safety	Destructive. This requires explicit human confirmation. Never auto-pass `--yes`. Preview first where a preview command exists.

Copy

ods config server remove https://localhost:44358

ods config server set

Sets a server-specific config value.

Arguments

<serverUrl>: server URL.

<key>: config key (authorityUrl, disableSslVerification).

<value>: config value.

Safety

Mutating (non-destructive). This may run autonomously. The agent may pass --yes to skip the interactive prompt.

Copy

ods config server set https://localhost:44358 disableSslVerification true

ods config set

Sets a config value by key. The value is parsed as JSON when possible, so booleans/numbers are stored typed, for example, true is converted to boolean true. Anything that is not valid JSON is stored as a string. To set a nested object, pass a JSON object literal as the value. This replaces the whole key (no deep merge), so update one field by reading the current value, editing it, and setting the whole object back.

Arguments

<key>: config key.

<value>: config value. This is parsed as JSON when valid, otherwise as a string.

Safety

Mutating (non-destructive). This may run autonomously. The agent may pass --yes to skip the interactive prompt.

Copy

ods config set authorityUrl https://idp.example.com
ods config set enableDarkMode true
ods config set assembliesApiTimeoutSeconds 120
ods config set someObject '{"nested":{"field":1}}'

Package Commands

ods package get

Downloads a package by type. For reference assemblies, this downloads the newest versions by default (or a pinned [version]) as a .nupkg into the current directory, or --output <dir>. With the --json flag, this emits the downloaded package metadata including the written path.

Arguments	`<type>`: package type. For example, reference assemblies. `[version]`: specific version to download. This defaults to the newest version.
Options	`-o, --output <dir>`: destination directory. This defaults to the current working directory.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods package get reference-assemblies
ods package get reference-assemblies 9.2.0
ods package get reference-assemblies --output ./libs

ods package list

With no argument, this lists the supported package types. With the type, this lists the versions available on the CDN with the newest first. With --json, this emits the array for scripting and agents.

Arguments	`[type]`: package type. For example, reference assemblies.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods package list
ods package list reference-assemblies
ods package list reference-assemblies --json

Repo Commands

ods repo add

Adds a repository definition to the shared ~/.ods/repositories store. An ID is generated automatically. A path that does not exist is accepted with a warning, matching the desktop client.

Arguments

<name>: repository display name.

<path>: absolute path to the repository folder.

Safety

Mutating (non-destructive). This may run autonomously. The agent may pass --yes to skip the interactive prompt.

Supports --json. This emits the standard envelope.

Copy

ods repo add "My Repo" C:\repos\my-repo

ods repo edit

Updates a repository definition by ID or name. Provide --name and/or --path. At least one of these is required.

Arguments	`<repo>`: repository ID or name.
Options	`-n, --name <name>`: new display name. `-p, --path <path>`: new repository folder path.
Safety	Mutating (non-destructive). This may run autonomously. The agent may pass `--yes` to skip the interactive prompt.
Supports	`--json`. This emits the standard envelope.

Copy

ods repo edit "My Repo" --name "Renamed Repo"
ods repo edit 1a2b3c --path C:\repos\moved

ods repo list

Lists repository definitions from the shared ~/.ods/repositories store, the same list the desktop application names. With --json, this emits the array for scripting and agents, for example, resolve a path, then cd and push.

Aliases	`ls`
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods repo list
ods repo list --json

ods repo remove

Removes a repository definition by ID or name. This only removes the definition from the shared store. It never deletes the files on disk.

Aliases	`rm`
Arguments	`<repo>`: repository ID or name.
Safety	Destructive. This requires explicit human confirmation. Never auto-pass `--yes`. Preview first where a preview command exists.
Supports	`--json`. This emits the standard envelope.

Copy

ods repo remove "My Repo"
ods repo rm 1a2b3c --yes

Workspace Assembly Commands

ods workspace-assembly add

Creates a new Workspace assembly with project and mapping files.

Arguments [path]: project directory or file. This defaults to the current working directory.

Options

-n, --name <name>: name for the repository item.

-l, --language <language>: programming language. CSharp or VisualBasic.

-e, --existing: use an existing project file instead of creating one.

--assemblyName <assemblyName>: OneStream assembly or business rule name.

-w, --workspaceName <workspaceName>: Workspace name.

-m, --maintenanceUnitName <maintenanceUnitName>: maintenance unit name.

Safety

Mutating (non-destructive). This may run autonomously. The agent may pass --yes to skip the interactive prompt.

Copy

ods workspace-assembly add -n MyAssembly

ods workspace-assembly decrypt

Decrypts a specific Workspace assembly on the connected server.

Prerequisites

You must be connected first: ods connect <serverUrl>

An application must be selected: ods application use <name> or pass --application <name>.

Options

-w, --workspace <workspace>: Workspace name.

-n, --name <name>: assembly name.

-f, --files <files...>: File names to decrypt.

--password-stdin: read the decryption password from stdin. This is for non-interactive use.

Safety

Destructive. This requires explicit human confirmation. Never auto-pass --yes. Preview first where a preview command exists.

Copy

ods assembly decrypt -w W -n N -f File.cs
echo "$PASSWORD" | ods assembly decrypt -w W -n N -f File.cs --password-stdin

ods workspace-assembly edit

Edits an existing Workspace assembly mapping file.

Arguments [path]: mapping file or directory. This defaults to the current working directory.

Options

-n, --name <name>: name of the repository item. This is used to find the <name>.osmap file in a directory.

--assemblyName <assemblyName>: OneStream assembly or business rule name.

-w, --workspaceName <workspaceName>: Workspace name.

-m, --maintenanceUnitName <maintenanceUnitName>: maintenance unit name.

Safety

Mutating (non-destructive). This may run autonomously. The agent may pass --yes to skip the interactive prompt.

Copy

ods workspace-assembly edit -n MyAssembly

ods workspace-assembly encrypt

Encrypts a specific Workspace assembly on the connected server.

Prerequisites

You must be connected first: ods connect <serverUrl>

An application must be selected: ods application use <name> or pass --application <name>.

Options

-w, --workspace <workspace>: Workspace name.

-n, --name <name>: assembly name.

-f, --files <files...>: File names to encrypt.

--password-stdin: read the encryption password from stdin. This is for non-interactive use.

Safety

Destructive. This requires explicit human confirmation. Never auto-pass --yes. Preview first where a preview command exists.

Copy

ods assembly encrypt -w W -n N -f File.cs
echo "$PASSWORD" | ods assembly encrypt -w W -n N -f File.cs --password-stdin

ods workspace-assembly files

Gets the files of a specific Workspace assembly from the connected server.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Options	`-w, --workspace <workspace>`: Workspace name. `-n, --name <name>`: assembly name.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods assembly files --workspace W --name N

ods workspace-assembly get

Gets a specific Workspace assembly from the connected server.

Prerequisites	You must be connected first: `ods connect <serverUrl>` An application must be selected: `ods application use <name>` or pass `--application <name>.`
Options	`-w, --workspace <workspace>`: Workspace name. `-n, --name <name>`: assembly name.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods assembly get --workspace W --name N

ods workspace-assembly list

Lists Workspace assembly items. It shows local mapping files by default or server items if you use --remote.

Arguments	`[path]`: path to list local items from. This defaults to the current working directory. This is ignored with `--remote`.
Options	`--remote`: list items on the connected server instead of local mapping files. `--workspace <workspace>`: filter server results by Workspace name. This requires `--remote`.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods assembly list
ods assembly list --json
ods assembly list --remote
ods assembly list --remote --json
ods assembly list --remote --workspace MyWorkspace

ods workspace-assembly remove

Removes Workspace assembly mapping files.

Aliases	`rm`
Arguments	`[path]`: mapping file or directory. This defaults to the current working directory.
Safety	Destructive. This requires explicit human confirmation. Never auto-pass `--yes`. Preview first where a preview command exists.

Copy

ods workspace-assembly remove ./src/MyItem

XF Project Commands

ods xf-project list

Lists XF Project manifests (.xfproj) on disk.

Aliases	`ls`
Arguments	`[path]`: path to scan for .xfproj manifests. This defaults to the current working directory.
Safety	Read. Safe to run autonomously and makes no changes.
Supports	`--json`. This emits the standard envelope.

Copy

ods xfproj list
ods xfproj list --json
ods xfproj list ./repo